/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.net.tftp;
import java.net.DatagramPacket;
import java.net.InetAddress;
/***
* TFTPPacket is an abstract class encapsulating the functionality common
* to the 5 types of TFTP packets. It also provides a static factory
* method that will create the correct TFTP packet instance from a
* datagram. This relieves the programmer from having to figure out what
* kind of TFTP packet is contained in a datagram and create it himself.
* <p>
* Details regarding the TFTP protocol and the format of TFTP packets can
* be found in RFC 783. But the point of these classes is to keep you
* from having to worry about the internals. Additionally, only very
* few people should have to care about any of the TFTPPacket classes
* or derived classes. Almost all users should only be concerned with the
* {@link org.apache.commons.net.tftp.TFTPClient} class
* {@link org.apache.commons.net.tftp.TFTPClient#receiveFile receiveFile()}
* and
* {@link org.apache.commons.net.tftp.TFTPClient#sendFile sendFile()}
* methods.
* <p>
* <p>
* @author Daniel F. Savarese
* @see TFTPPacketException
* @see TFTP
***/
public abstract class TFTPPacket
{
/***
* The minimum size of a packet. This is 4 bytes. It is enough
* to store the opcode and blocknumber or other required data
* depending on the packet type.
***/
static final int MIN_PACKET_SIZE = 4;
/***
* This is the actual TFTP spec
* identifier and is equal to 1.
* Identifier returned by {@link #getType getType()}
* indicating a read request packet.
***/
public static final int READ_REQUEST = 1;
/***
* This is the actual TFTP spec
* identifier and is equal to 2.
* Identifier returned by {@link #getType getType()}
* indicating a write request packet.
***/
public static final int WRITE_REQUEST = 2;
/***
* This is the actual TFTP spec
* identifier and is equal to 3.
* Identifier returned by {@link #getType getType()}
* indicating a data packet.
***/
public static final int DATA = 3;
/***
* This is the actual TFTP spec
* identifier and is equal to 4.
* Identifier returned by {@link #getType getType()}
* indicating an acknowledgement packet.
***/
public static final int ACKNOWLEDGEMENT = 4;
/***
* This is the actual TFTP spec
* identifier and is equal to 5.
* Identifier returned by {@link #getType getType()}
* indicating an error packet.
***/
public static final int ERROR = 5;
/***
* The TFTP data packet maximum segment size in bytes. This is 512
* and is useful for those familiar with the TFTP protocol who want
* to use the {@link org.apache.commons.net.tftp.TFTP}
* class methods to implement their own TFTP servers or clients.
***/
public static final int SEGMENT_SIZE = 512;
/*** The type of packet. ***/
int _type;
/*** The port the packet came from or is going to. ***/
int _port;
/*** The host the packet is going to be sent or where it came from. ***/
InetAddress _address;
/***
* When you receive a datagram that you expect to be a TFTP packet, you use
* this factory method to create the proper TFTPPacket object
* encapsulating the data contained in that datagram. This method is the
* only way you can instantiate a TFTPPacket derived class from a
* datagram.
* <p>
* @param datagram The datagram containing a TFTP packet.
* @return The TFTPPacket object corresponding to the datagram.
* @exception TFTPPacketException If the datagram does not contain a valid
* TFTP packet.
***/
public final static TFTPPacket newTFTPPacket(DatagramPacket datagram)
throws TFTPPacketException
{
byte[] data;
TFTPPacket packet = null;
if (datagram.getLength() < MIN_PACKET_SIZE)
throw new TFTPPacketException(
"Bad packet. Datagram data length is too short.");
data = datagram.getData();
switch (data[1])
{
case READ_REQUEST:
packet = new TFTPReadRequestPacket(datagram);
break;
case WRITE_REQUEST:
packet = new TFTPWriteRequestPacket(datagram);
break;
case DATA:
packet = new TFTPDataPacket(datagram);
break;
case ACKNOWLEDGEMENT:
packet = new TFTPAckPacket(datagram);
break;
case ERROR:
packet = new TFTPErrorPacket(datagram);
break;
default:
throw new TFTPPacketException(
"Bad packet. Invalid TFTP operator code.");
}
return packet;
}
/***
* This constructor is not visible outside of the package. It is used
* by subclasses within the package to initialize base data.
* <p>
* @param type The type of the packet.
* @param address The host the packet came from or is going to be sent.
* @param port The port the packet came from or is going to be sent.
**/
TFTPPacket(int type, InetAddress address, int port)
{
_type = type;
_address = address;
_port = port;
}
/***
* This is an abstract method only available within the package for
* implementing efficient datagram transport by elminating buffering.
* It takes a datagram as an argument, and a byte buffer in which
* to store the raw datagram data. Inside the method, the data
* should be set as the datagram's data and the datagram returned.
* <p>
* @param datagram The datagram to create.
* @param data The buffer to store the packet and to use in the datagram.
* @return The datagram argument.
***/
abstract DatagramPacket _newDatagram(DatagramPacket datagram, byte[] data);
/***
* Creates a UDP datagram containing all the TFTP packet
* data in the proper format.
* This is an abstract method, exposed to the programmer in case he
* wants to implement his own TFTP client instead of using
* the {@link org.apache.commons.net.tftp.TFTPClient}
* class.
* Under normal circumstances, you should not have a need to call this
* method.
* <p>
* @return A UDP datagram containing the TFTP packet.
***/
public abstract DatagramPacket newDatagram();
/***
* Returns the type of the packet.
* <p>
* @return The type of the packet.
***/
public final int getType()
{
return _type;
}
/***
* Returns the address of the host where the packet is going to be sent
* or where it came from.
* <p>
* @return The type of the packet.
***/
public final InetAddress getAddress()
{
return _address;
}
/***
* Returns the port where the packet is going to be sent
* or where it came from.
* <p>
* @return The port where the packet came from or where it is going.
***/
public final int getPort()
{
return _port;
}
/*** Sets the port where the packet is going to be sent. ***/
public final void setPort(int port)
{
_port = port;
}
/*** Sets the host address where the packet is going to be sent. ***/
public final void setAddress(InetAddress address)
{
_address = address;
}
}